---
title: Overview
description: "How rate limiting works in unkey"
---

Unkey's ratelimiting system controls the number of requests a key can make within a given timeframe. This prevents abuse, protects your API from being overwhelmed, and enables usage-based billing models.

## Multi-Ratelimit System

Unkey supports multiple named ratelimits per key, providing fine-grained control over different aspects of your API usage. You can define separate limits for different operations, time windows, and use cases within a single key.

The system offers two types of ratelimits: auto-apply ratelimits that check automatically during verification, and manual ratelimits that require explicit specification in requests.

## Auto-Apply vs Manual Ratelimits

Auto-apply ratelimits (`autoApply: true`) are checked automatically during every key verification without needing explicit specification. These work well for general usage limits that should always be enforced.

```bash
# Create a key with auto-apply ratelimit
curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "api_123",
    "ratelimits": [
      {
        "name": "general-requests",
        "limit": 100,
        "duration": 60000,
        "autoApply": true
      }
    ]
  }'
```

```bash
# Verify key - auto-apply ratelimits are checked automatically
curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "your_api_key_here"
  }'
```

Manual ratelimits (`autoApply: false`) must be explicitly specified in verification requests. Use these for operation-specific limits that only apply to certain endpoints.

```bash
# Create a key with manual ratelimit
curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "api_123",
    "ratelimits": [
      {
        "name": "expensive-operations",
        "limit": 5,
        "duration": 60000
      }
    ]
  }'
```

```bash
# Verify key - override cost explicitly
curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "your_api_key_here",
    "ratelimits": [
      {
        "name": "expensive-operations",
        "cost": 2
      }
    ]
  }'
```

## Configuration

Configure ratelimits on a per-key or per-identity basis through the dashboard or API. Each ratelimit requires a unique name, limit count, and duration in milliseconds.

```bash
curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "api_123",
    "ratelimits": [
      {
        "name": "requests",
        "limit": 100,
        "duration": 60000,
        "autoApply": true
      },
      {
        "name": "daily-quota",
        "limit": 1000,
        "duration": 86400000,
        "autoApply": true
      }
    ]
  }'
```

You can apply different costs to operations by specifying a cost parameter during verification. This allows resource-intensive operations to consume more of the rate limit than simple operations.

## Identity-Level Ratelimits

Configure ratelimits at the identity level to share limits across multiple keys. Identity ratelimits work alongside key-level ratelimits, with key-level settings taking precedence for naming conflicts.

```bash
curl -X POST https://api.unkey.com/v2/identities.createIdentity \
  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_123",
    "ratelimits": [
      {
        "name": "user-requests",
        "limit": 1000,
        "duration": 3600000
      }
    ]
  }'
```

This approach works well for user-based quotas where multiple API keys should share the same usage limits.
